Obtains location information for system-related directories.

OSErr FindFolder (
    SInt16 vRefNum, 
    OSType folderType, 
    Boolean createFolder, 
    SInt16 *foundVRefNum, 
    SInt32 *foundDirID
);

Parameter descriptions

vRefNum

Pass the volume reference number (or the constant kOnSystemDisk for the startup disk) of the volume on which you want to locate a directory; see “Volume Constant”.

folderType

Pass a four-character folder type, or a constant that represents the type, for the folder you want to find; see “Folder Type Constants”.

createFolder

A value of type Boolean, as defined in “Create Folder Flag Constants”. Pass the constant kCreateFolder to create a directory if it does not already exist; otherwise, pass the constant kDontCreateFolder. Directories inside the System Folder are created only if the System Folder directory exists. The FindFolder function will not create a System Folder directory even if you specify the kCreateFolder constant in the createFolder parameter. Passing kCreateFolder will also not create a parent folder; if the parent of the target folder does not already exist, attempting to create the target will fail.

foundVRefNum

A pointer to a value of type short. On return, the value specifies the volume reference number for the volume containing the directory specified in the folderType parameter.

foundDirID

A pointer to a value of type long. On return, the value specifies the directory ID number for the directory specified in the folderType parameter.

function result

A result code. The result code fnfErr indicates that the type has not been found in the 'fld#' resource, or the disk doesn’t have System Folder support, or the disk does not have desktop database support for Desktop Folder—in all cases, the folder has not been found. The result code dupFNErr indicates that a file has been found instead of a folder.

DISCUSSION

As of Mac OS 8 and later, your application can add folders to the System Folder—or nest folders within other folders—and locate the folders via the FindFolder function. Prior to Mac OS 8, your application could only use FindFolder to find folders that were immediately inside of the System Folder, and a few other special folders such as the Trash folder and the System Folder itself. Now, once a folder (and any folders that it is nested within) is described in a folder descriptor—that is, registered using the function AddFolderDescriptor—your application can use FindFolder to find the folder no matter where it is located.

Those folders you’re most likely to want to access are Preferences and Trash. For example, you might wish to check for the existence of a user’s configuration file in Preferences or, if your application runs out of disk storage when trying to save a file, check how much disk storage is taken by items in the Trash directory and report this to the user.

The specified folder used for a given volume might be located on a different volume in future versions of system software; therefore, do not assume the volume that you specify in vRefNum and the volume returned through foundVRefNum will be the same.

SPECIAL CONSIDERATIONS

Prior to Mac OS 8, the Finder identified the subdirectories of the System Folder, and their folder types, in a resource of type 'fld#' located in the System file. While some backwards compatibility support for 'fld#' remains, it has been superseded by the 'nfd#' resource under Mac OS 8 and later. As with 'fld#', you should not modify or rely on the contents of the 'nfd#' resource in the System file. Instead, use only the FindFolder function to find the appropriate folders, and use the functions AddFolderDescriptor and RemoveFolderDescriptor to modify folder descriptors.

VERSION NOTES

Available under System 7 and later.

Changed in Mac OS 8 to support finding folders registered using the function AddFolderDescriptor.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)